gh-97517: Add hyperlink to format code information for strftime() and strptime() docstrings.#132375
gh-97517: Add hyperlink to format code information for strftime() and strptime() docstrings.#132375PlayfulPiano wants to merge 1 commit intopython:mainfrom
Conversation
|
All commit authors signed the Contributor License Agreement. |
|
Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool. If this change has little impact on Python users, wait for a maintainer to apply the |
PlayfulPiano
changed the title
|
A recursive link? It is meant to link to an issue, not the same pr :-) In this case there is an existing issue: #97517 You need to sign the CLA, and I would also recommend reading the devguide. |
StanFromIreland
left a comment
StanFromIreland
left a comment
There was a problem hiding this comment.
The docs strings are not .rst/.md files and are not used to generate them here, you need simpler linking.
e.g.
A list of ...:
https://docs.python.org/3/...
oh my bad, I misread the template text. Was confused why it wanted to use the PR number when you wouldn't have access to it until after making the PR. I did sign the CLA though. Unsure why it didn't update. https://cla.python.org/view/80712991-7cd2-4933-8b47-2db40d5596e4/
Huh. I was searching for the clickable hyperlink format for a python docstring and it said to use the pr's syntax. It worked fine when I made the same edits locally when viewing it under VSCode's documentation method tooltip. Would the syntax you mentioned allow link clicking too? |
PlayfulPiano
changed the title
ZeroIntensity
left a comment
ZeroIntensity
left a comment
There was a problem hiding this comment.
We generally don't use Sphinx markup like this in docstrings, because help() can't render it. I'm not 100% sure what the best way to deal with this is.
Note that this PR looks like it's trying to do the same thing as #31761.
|
In that PR we came to the conclusion it should be a link and the PR owner has not updated the PR for quite a while so this is fine. As for the markup please just make it a simple link like I mentioned before. |
StanFromIreland
left a comment
StanFromIreland
left a comment
There was a problem hiding this comment.
You also need to update the C docstrings:
cpython/Modules/_datetimemodule.c
Line 3916 in b330897
cpython/Modules/_datetimemodule.c
Line 3929 in b330897
cpython/Modules/_datetimemodule.c
Line 5158 in b330897
cpython/Modules/_datetimemodule.c
Line 5143 in b330897
cpython/Modules/_datetimemodule.c
Line 7028 in b330897
|
|
||
| Example: "%d/%m/%Y, %H:%M:%S" | ||
|
|
||
| `A list of supported format codes can be viewed here. <https://docs.python.org/3/library/datetime.html#format-codes>`_ |
There was a problem hiding this comment.
| `A list of supported format codes can be viewed here. <https://docs.python.org/3/library/datetime.html#format-codes>`_ | |
| For a list of supported format codes, see the documentation: | |
| https://docs.python.org/3/library/datetime.html#format-codes |
| """Format using strftime(). The date part of the timestamp passed | ||
| to underlying strftime should not be used. | ||
|
|
||
| `A list of supported format codes can be viewed here. <https://docs.python.org/3/library/datetime.html#format-codes>`_ |
There was a problem hiding this comment.
| `A list of supported format codes can be viewed here. <https://docs.python.org/3/library/datetime.html#format-codes>`_ | |
| For a list of supported format codes, see the documentation: | |
| https://docs.python.org/3/library/datetime.html#format-codes |
| 'string, format -> new datetime parsed from a string (like time.strptime()).' | ||
| """string, format -> new datetime parsed from a string (like time.strptime()). | ||
|
|
||
| `A list of supported format codes can be viewed here. <https://docs.python.org/3/library/datetime.html#format-codes>`_""" |
There was a problem hiding this comment.
| `A list of supported format codes can be viewed here. <https://docs.python.org/3/library/datetime.html#format-codes>`_""" | |
| For a list of supported format codes, see the documentation: | |
| https://docs.python.org/3/library/datetime.html#format-codes | |
| """ |
3 participants
Fairly self-explanatory PR. Whenever I've used the datetime library, I've commonly had to open up the format code documentation in my web browser. This is just an inclusion of a link to the official python documentation so end users can more quickly/easily access this information. Plus it synergizes well with documentation extensions like VSCode's Docs View.
It might be worthwhile to port the full format code documentation, but I figured this would be a nice QoL addition without concern about how the documentation should be structured in the docstring.